General | | | |
| Before doing any integration work, we recommend you start by mapping out the processes in the customer warehouse and draw diagrams. This will give a clearer picture of what the integration should cover and it’s a good basis for future discussions. It doesn’t have to be overly detailed or complex, but it should include all steps creating new data points or interacting with external systems. | | | |
| You should host your integration somewhere accessible for the Pio platform, and give it a static URL. Use the URL to register for webhooks from Pio (see hooks) | | | |
Authentication | | | |
| You should have taken an active decision if your integration needs to support a multi tenant setup or if you only need to handle one single shop/customer/order channel. | | | |
Shops | | | |
| Once the authentication and authorization of the integration is done, a shop must be created before products and orders can be added. | | | |
Products | | | |
| Product information from your external system (ERP, WMS, e-commerce platform or similar) needs to be synchronised with Pio. This means that any new product added to external system needs to be created in Pio. When creating the product, include as much meta data as possible. Brand, type etc can be valuable for Pios internal handling. | | | |
| Any updates or changes needs to be updated in Pio. | | | |
| When removing a product in the external system, the integration needs to consider whether that product has stock in Pio or not. If it does not, it can safely be deleted in Pio. If it does have stock, it is advisable that the stock be removed from Pio before deleting the product. | | | |
| To identify a product within Pio it needs a unique SKU. If there is a unique SKU in your external system that can be used directly when creating products in Pio. If not, you have to take measures to create a SKU based on the information you have in your external system that makes it unique. One example could be to concatenate a Product ID and a Variant ID. | | | |
| In Pio we show product images if one is provided. By specifying a URL to a hosted image when creating the product we will show this as needed. | | | |
| React accordingly to inventory level updates: When your integration receives inventory level updates, it's important to note that there are three numbers to take into account, in_stock, reserved and available. Your integration should react accordingly to these levels. | | | |
| When using purchase order, you should react accordingly to purchase order updates and purchase order sync webhook messages. | | | |
Orders | | | |
| Orders need to be synced over to Pio. Extra information like tags, notes, selected shipping rates etc should also be included. When doing so, it may be worth considering which orders get synced over. Should all your incoming order get sent over or should orders in a specific state/status get sent over. | | | |
| Tags, note, destination address can be updated on the fly. If any of the order lines have change you need to delete/re-create the order. | | | |
| If an order gets cancelled this also need to get deleted in Pio. If the order has already been picked by the time of cancelling, it should follow some kind of return flow. | | | |
| When receiving an update from Pio that the order has been fulfilled, this should be reflected in the external system. | | | |
Shipping | | | |
| You should have made a decision on how you want to handle shipping. You can either use one of our ready-made integrations (Webshipper/Shipstation) or you can make your own shipping integration. Either way you should consider the value of adding this integration to Pio. This will help speed up operations while picking, eliminating the picker having to interact with several systems while doing pick and pack. | | | |
| If you are using a shipping platform (Webshipper or Shipstation) these need to be connected through the integrations page in the Admin view. | | | |
| It is important that the order number given to the shipping platform is the same as Pio receives. This is what we use to match an order to its corresponding shipment order. | | | |
Webhooks | | | |
| Upon receiving webhooks from Pio, you should acknowledge and respond in a timely manner (current timeout 5 secs). If local processing is needed, store the event in a queue and handle it asynchronously. Webhooks not responding within timeout are considered failed and will be retried from Pio. | | | |
| When receiving inventory level updates, you should make sure to handle your inventory levels based on what is reported back in the webhook message. | | | |